<para>
Each animation frame can have several things happen to it when the
next frame is displayed. The #GdkPixbufFrameAction determines this.
- If a frame as marked as @GDK_PIXBUF_FRAME_RETAIN, then the image
+ If a frame as marked as #GDK_PIXBUF_FRAME_RETAIN, then the image
will remain displayed, and will be potentially occluded by the next
- frame. If it is marked as @GDK_PIXBUF_FRAME_DISPOSE, then the
+ frame. If it is marked as #GDK_PIXBUF_FRAME_DISPOSE, then the
animation is reverted to the setting before the frame was shown. If
- it is marked as @GDK_PIXBUF_FRAME_REVERT, then the animation is
+ it is marked as #GDK_PIXBUF_FRAME_REVERT, then the animation is
reverted to the first image before continuing.
</para>
GdkPixbufLoader
<!-- ##### SECTION Short_Description ##### -->
-Application-driven image loading.
+Application-driven progressive image loading.
<!-- ##### SECTION Long_Description ##### -->
<para>
#GdkPixbufLoader provides a way for applications to drive the
- process of loading an image. Applications can use this
- functionality instead of gdk_pixbuf_new_from_file() when they need
- to parse image data in small chunks, such as when reading it from
- a network connection.
+ process of loading an image, by letting them send the image data
+ directly. Applications can use this functionality instead of
+ gdk_pixbuf_new_from_file() when they need to parse image data in
+ small chunks. For example, it should be used when reading an image
+ from a (potentially) slow network connection, or when loading an
+ extremely large file.
</para>
-
+ <para>
+ To use #GdkPixbufLoader to load an image, just create a new one, and
+ call gdk_pixbuf_loader_write() to send the data to it. When done,
+ gdk_pixbuf_loader_close() should be called to end the stream and
+ finalize everything. The loader will emit two important signals
+ throughout the process. The first, #"area_prepared", will be called
+ as soon as the image has enough information to determine the size of
+ the image to be used. It will pass a @GdkPixbuf in. If you want to
+ use it, you can simply ref it. In addition, no actual information
+ will be passed in yet, so the pixbuf can be safely filled with any
+ temporary graphics (or an initial color) as needed. You can also
+ call the gdk_pixbuf_loader_get_pixbuf() once this signal has been
+ emitted and get the same pixbuf.
+ </para>
+ <para>
+ The other signal, #"area_updated" gets called every
+ time a region is updated. This way you can update a partially
+ completed image. Note that you do not know anything about the
+ completeness of an image from the area updated. For example, in an
+ interlaced image, you need to make several passes before the image
+ is done loading.
+ </para>
+ <refsect2>
+ <title>Loading an animation</title>
+ <para>
+ Loading an animation is a little more complex then loading an
+ image. In addition to the above signals, there is also a
+ #"frame_done" signal, as well as an #"animation_done" signal. The
+ first lets the application know that it is dealing with an
+ animation, instead of a static image. It also passes a
+ #GdkPixbufFrame in the signal. As before, if you want to keep the
+ frame, you need to ref it. Once the first #"frame_done" signal
+ has been emitted, you can call gdk_pixbuf_loader_get_animation()
+ to get the #GdkPixbufAnimation struct. Each subsequent frame goes
+ through a similar lifecycle. For example #"area_prepared" is
+ re-emitted. Then #"area_updated" is emitted as many times as
+ necessary. Finally, #"animation_done" is emitted as soon as all
+ frames are done.
+ </para>
+ </refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
gdk_pixbuf_new_from_file()
projects / gtk4.git / commitdiff